home *** CD-ROM | disk | FTP | other *** search
/ The Atari Compendium / The Atari Compendium (Toad Computers) (1994).iso / files / prgtools / mint / mntdoc01.zoo / mintdoc / cat2 / psemaphore.nr < prev    next >
Encoding:
Text File  |  1993-03-03  |  4.2 KB  |  133 lines
  1.  
  2.  
  3.  
  4. Psemaphore(2)              Jan. 6, 1992             Psemaphore(2)
  5.  
  6.  
  7. N✓NA✓AM✓ME✓E
  8.        Psemaphore - create / use / destroy a sempahore
  9.  
  10. S✓SY✓YN✓NO✓OP✓PS✓SI✓IS✓S
  11.        LONG Psemaphore( WORD mode, LONG id, LONG timeout );
  12.  
  13. D✓DE✓ES✓SC✓CR✓RI✓IP✓PT✓TI✓IO✓ON✓N
  14.        _✓P_✓s_✓e_✓m_✓a_✓p_✓h_✓o_✓r_✓e is a call that implements uncounted semaphores.
  15.        A semaphore is used for mutual exclusion: only one process
  16.        at a time may "own" a given semaphore.
  17.  
  18.        For  example, a semaphore may be used to protect access to
  19.        data structures which are in shared memory and  which  are
  20.        used  by  multiple  threads in a process: before using the
  21.        memory a  thread  must  gain  ownership  of  the  guarding
  22.        semaphore,  and  when finished the thread must release the
  23.        semaphore. The semaphore would be created during  initial-
  24.        ization and destroyed during shutdown.
  25.  
  26.        Semaphores  are identified by an _✓i_✓d, which is an arbitrary
  27.        longword.  This is the semaphore's "name." The _✓i_✓d used  to
  28.        create  the semaphore is the "name" of that semaphore from
  29.        then on.  When using semaphores, you should strive to  use
  30.        a  longword  that  is  unique. Using four ASCII characters
  31.        which spell out something is common:  0x4b4f444f  ("MODM")
  32.        for  instance might be the _✓i_✓d of a semaphore that controls
  33.        access to a  modem.   (Actually,  this  would  be  a  poor
  34.        choice, since there can be more than one modem in a system
  35.        and this semaphore ID  isn't  flexible  enough  to  handle
  36.        that.  "MDM1" might be better.)
  37.  
  38.        Semaphore id's beginning with 0x5f (the underscore charac-
  39.        ter) are reserved for operating system use.
  40.  
  41.        The _✓t_✓i_✓m_✓e_✓o_✓u_✓t argument is only used in Mode 2. It is ignored
  42.        in  other  modes.  A _✓t_✓i_✓m_✓e_✓o_✓u_✓t of zero means "return immedi-
  43.        ately."  A value of -1 means "forever" -  that  is,  never
  44.        time  out.  Other  values  are a number of milliseconds to
  45.        wait for the semaphore before timing out.
  46.  
  47.        The _✓m_✓o_✓d_✓e argument is  used  to  tell  what  operation  the
  48.        caller desires:
  49.  
  50.  
  51.        MODE   ACTION
  52.  
  53.        0      Create and "get" a semaphore with the given ID.
  54.  
  55.        1      Destroy  the  indicated  semaphore. The caller must
  56.               own the semaphore prior to making this call.
  57.  
  58.        2      Request ownership of the  semaphore.  Blocks  until
  59.               the semaphore is free or until the timeout expires.
  60.               See below.
  61.  
  62.  
  63.  
  64. Version 0.92         MiNT Programmer's Manual                   1
  65.  
  66.  
  67.  
  68.  
  69.  
  70. Psemaphore(2)              Jan. 6, 1992             Psemaphore(2)
  71.  
  72.  
  73.        3      Release the semaphore.  The  caller  must  own  the
  74.               semaphore prior to making this call.
  75.  
  76. R✓RE✓ET✓TU✓UR✓RN✓NS✓S
  77.        CODE   MEANING
  78.  
  79.        0      Success.
  80.  
  81.        ERROR  A  request for a semaphore which the caller already
  82.               owns.
  83.  
  84.        ERANGE The semaphore does not exist.
  85.  
  86.        EACCDN Failure. The semaphore already exists (mode 0), you
  87.               don't  own it (modes 1 and 3), or the request timed
  88.               out (mode 2).
  89.  
  90.  
  91. N✓NO✓OT✓TE✓ES✓S
  92.        When you create a semaphore you also own it, so  you  must
  93.        release  it  before  anybody  else  can get it. If you are
  94.        blocked waiting for a semaphore (mode 2 before the timeout
  95.        expires)  and  somebody  destroys  the semaphore, the call
  96.        will return ERANGE to you (because the requested semaphore
  97.        does not exist any more!).
  98.  
  99.        When  a  process  terminates,  any  semaphores it owns are
  100.        released.
  101.  
  102.        At most one process may own a semaphore.  Ownership is not
  103.        inherited by children (fork()) or across exec().
  104.  
  105.        Once  created,  semaphores are never destroyed except upon
  106.        request. Thus if a program creates a  semaphore  and  then
  107.        crashes the semaphore will never go away.
  108.  
  109.        Semaphores  can  be implemented using named pipes and file
  110.        locking. Technically, then, semaphores are redundant.  The
  111.        facility  is  included  as  a  kernel  call because it was
  112.        deemed necessary to have this kind of exclusion  available
  113.        with little persistent state or system-call overhead.
  114.  
  115.  
  116.  
  117.  
  118.  
  119.  
  120.  
  121.  
  122.  
  123.  
  124.  
  125.  
  126.  
  127.  
  128.  
  129.  
  130. Version 0.92         MiNT Programmer's Manual                   2
  131.  
  132.  
  133.